package cmpe273.proj1.dao;

import java.util.List;

import cmpe273.proj1.model.Course;
import cmpe273.proj1.model.Student;

/**
 * This interface represents a contract for a DAO for the {@link Student} model.
 *
 * @author BalusC
 * @link http://balusc.blogspot.com/2008/07/dao-tutorial-data-layer.html
 */
public interface StudentDAO {

    // Actions ------------------------------------------------------------------------------------

	/**
     * Returns the Student from the database matching the given ID, otherwise null.
     * @param id The ID of the Student to be returned.
     * @return The Student from the database matching the given ID, otherwise null.
     *   Note: individual students will be returned with their courses (will JOIN)
     * @throws DAOException If something fails at database level.
     */
    public Student find(Long id) throws DAOException;
    
    /**
     * Returns the Student from the database matching the given SSN style ID, otherwise null.
     * @param id The SSN style ID of the Student to be returned.
     * @return The Student from the database matching the given ID, otherwise null.
     *   Note: individual students will be returned with their courses (will JOIN)
     * @throws DAOException If something fails at database level.
     */
    public Student find(String id) throws DAOException;

    /**
     * Returns a list of all Students from the database ordered by Student ID. The list is never null and
     * is empty when the database does not contain any Student.
     * @param count Fetch instructors in batches of count (max 100)
     * @param page Fetch instructors in batches of count, returning the "page" page (1-indexed)
     * @param Flag to get basic student information (name, address, etc.) vs. getting full students with 
     *   course information, which requires JOIN
     * @return A list of all Students from the database ordered by Student ID.
     * @throws DAOException If something fails at database level.
     */
    public List<Student> list(int count, int page, boolean getCourses) throws DAOException;
    
    /**
     * Returns a list of all Students from the database ordered by Student ID that match non-null parameters.
     * The list is never null and is empty when the database does not contain any Student.
     * @param searchParams A Student object where those parameters to search by are not-null.
     * Search for strings is "LIKE '%param%'" (i.e. contains), search for integers is exact
     * Note: does not search for students by course -- use searchStudentsEnrolledIn method for this
     * @param getCourses Flag to get basic student information (name, address, etc.) vs. getting full students with 
     *   course information, which requires JOIN
     * @return A list of all Students from the database ordered by Student ID that match search parameters.
     * @throws DAOException If something fails at database level.
     */
    public List<Student> search(Student searchParams, boolean getCourses) throws DAOException;
    
    /**
     * Returns a list of all Students from the database ordered by Student ID that are part of the input course.
     * The list is never null and is empty when the database does not contain any Student.
     * @param course A Course object representing the course to look for
     * @return A list of all Students from the database ordered by Student ID that match search parameters.
     * @throws DAOException If something fails at database level.
     */
    public List<Student> searchStudentsEnrolledIn(Course course) throws DAOException;

    /**
     * Create the given Student in the database. The Student ID must be null, otherwise it will throw
     * IllegalArgumentException. After creating, the DAO will set the obtained ID in the given Student.
     * @param s The Student to be created in the database.
     * @throws IllegalArgumentException If the Student ID is not null.
     * @throws DAOException If something fails at database level.
     */
    public void create(Student s) throws IllegalArgumentException, DAOException;

    /**
     * Update the given Student in the database. The Student ID must not be null, otherwise it will throw
     * IllegalArgumentException.  Password will not be updated.
     * @param s The Student to be updated in the database.
     * @throws IllegalArgumentException If the Student ID is null.
     * @throws DAOException If something fails at database level.
     */
    public void update(Student s) throws IllegalArgumentException, DAOException;
    
    /**
     * Update the given Student in the database. The Student ID must not be null, otherwise it will throw
     * IllegalArgumentException.
     * @param s The Student to be updated in the database.
     * @param c The Course to enroll the student in.
     * @throws IllegalArgumentException If the Student ID is null.
     * @throws DAOException If something fails at database level.
     */
    public void addCourse(Student s, Course c) throws IllegalArgumentException, DAOException;

    /**
     * Update the given Student in the database. The Student ID must not be null, otherwise it will throw
     * IllegalArgumentException.
     * @param s The Student to be updated in the database.
     * @param c The Course to unenroll the student from.
     * @throws IllegalArgumentException If the Student ID is null.
     * @throws DAOException If something fails at database level.
     */
    public void removeCourse(Student s, Course c) throws IllegalArgumentException, DAOException;
    
    /**
     * Delete the given Student from the database. After deleting, the DAO will set the ID of the given
     * Student to null.
     * @param s The Student to be deleted from the database.
     * @throws DAOException If something fails at database level.
     */
    public void delete(Student s) throws DAOException;
}